Workflow Designer - Overview

The Workflow Designer screen provides the primary interface for creating and managing Workflows within the platform. The Workflow Designer window can be opened from ADMINISTRATION, Content Management, Workflow Designer.

Actions Palette

The actions palette will show all available categories of actions. Selecting a category will open up that category to show all its available actions. Or, using the Filter box above the category list, you can type in a search string (or partial string) to filter down and find specific available actions, broken out by category. NOTE: In addition to the “stock” or “out of box” actions, PMG’s application typically ships with some number of custom actions (or “connectors”) as well. Custom connector actions are used to integrate the platform with separate systems or third party solutions, such as HR Management or Help Desk ticketing systems. So, based on the nature of the installation, there could be other categories of custom activities available within the actions palette.

The Designer Canvas

Workflow administrators drag and drop actions from the palette on the left side of the designer, onto the canvas window.

Configured actions are then linked together with output connections to design the desired sequence and flow logic.

Each action has properties which may be set with the properties panel which is displayed on the right side of the designer. To show the properties panel for a given action, right click the action and select “Properties”.

Palette menu, layout support

Actions can be added to the canvas with a default spacing by right clicking the action in the palette and choosing an option for placement. The “Add to…” options will insert and connect the action relative to a currently selected action in the canvas. “Insert In-between” will add the action to a selected line in the canvas.

Replacing individual actions

Individual actions in the canvas may be replaced with another action type. To change or replace an action type, select the single action to be replaced within the canvas, and then from the palette, right click the new action type to use, and select “Replace Selected Action”. As appropriate, old values from the prior action will be brought into the new action type.

Action Properties Panel

The Action Properties Panel contains a series of fields where all the configurable properties or settings for each action can be defined. The Action Properties panel will appear on the right side of the Workflow Designer window, and is accessed by right clicking an action or line and selecting “Properties”.

When actions are initially added to the diagram, they are automatically named with the action type name plus an incremental number. To change the name of any action, use the “Name” property at the top of the properties window.

Changes made to action properties are immediately saved to the draft workflow definition.

Help – opens the selected Action’s online help content

Actions with many properties will provide a filter at the top of the properties window to facilitate finding the needed property quickly.

Global Actions Options

Right-Click Menu Options: Each action in the canvas will offer options when icon itself is right-clicked. The following is an overview of the functional right-click options available globally on all actions.

Properties

This option opens the Action Properties panel for the selected activity on the right side of the designer window, if it’s not currently open.

Delete – This option will delete the highlighted action entirely, including all its property settings and corresponding links to it.

Workflow Actions

Common Property Types

ID

Each action is given a unique, non-editable ID when created. The ID will generally be the action type, e.g. “Approval” and then the next incremented number for that action type within the diagram, so “Approval1” for the first, “Approval2” for the second. This ID is useful to distinctly identify the action within the workflow for troubleshooting as well as configuration options, such as the “Cancel Activity” action which can reference one or more specific actions.

Label

The Label property provides the option to provide distinguishing information about a given action. So, an Approval action might be labeled, “Purchase approval”, or a decision step might be labeled, “Check if within budget”.

Text

The Text property is a generic property type used for many scenarios, including setting display messages, general strings, SQL expressions, and constructing rich text (HTML). The property type supports input by directly typing into the text box provided for the property.

Additionally, the Text property provides a rich set of tools and editor options. To open the editor for a text property, click the pencil icon provided.

There are three editor interfaces available for the property.

Text Editor

The Text Editor interface provides an interface to edit the value as “text”, like Microsoft Notepad or other plain text editors. The editor supports a syntax feature to color highlight the text for simple validation. Syntax options include XML, Text, and SQL.

For example, the SQL option provides color syntax highlighting per below.

Rich Text Editor

The Rich Text Editor provides a WYSIWYG text editor to generate rich text as HTML.

Common, familiar rich text formatting controls are available, including color and font options, and HTML link management. The generated HTML can be viewed and edited in its raw form by choosing the “< >” source code option.

The Code Editor tab provides an interface to implement C# code to generate the returned value for the property.

The “Validate” button will check the syntax of the code and will also show the final code which will be generated and used for the code expression given.

Including workflow context in the editor

When editing text, the keyboard shortcut, “Ctrl-Spacebar” will load an in-place auto-complete feature to include any workflow context value in the text. After typing the shortcut, type some amount of the letters needed to filter the list further. Then use the arrow keys, or the mouse to scroll through options and use the enter key or mouse to click the value to insert.

Alternately, the workflow values can be browsed and selected by clicking “Context Variables”

Enter a filter string in the input box provided to search for a value, or click to expand a section and scroll to find and select a value.

Assign Actor(s)

Actions, which involve people as resources(typically user objects in a directory), support assignment to one or more individuals by setting matching rules.

The property screen has two modes: simple and advanced. The default is simple mode which allows a designer to specify a simple resource conditional statement with one or more conditions. Additional conditions are added with the “Add” button and can be deleted with the trashcan icon at the end of each row.

The Assign Actors property window offers radio buttons with two possible options:

• All of these are true (Default)

• Any of these are true

“All of these are true” acts like an “and” rule, meaning only find users who match all of the criteria.

“Any of these are true” acts as an “or” rule, meaning, match users where any of the conditions are true.

The Property field offers a drop-down list of available attributes that can be matched on or compared against in each condition. The Operator field includes options like “equals,” “not equal to,” “contains” or “in,” which is then applied against the entry in the Value or Variable field when compared to the selected Property. The eraser icon can be used to clear out the entries in each row, and the trash can icon is used to delete a given row.

Note: The “In” operator supports matching a user property from an array or AD Group.

For assigning actors using rules more complex than simple matching of properties, or where a combination of “and” and “or” rules is required, use the “Advanced Editor” by clicking “Enable Advanced Editor.” This interface provides a rich rules-based editor to build more complex matching rules like below.

Parentheses may also be used to group logic like below.

Assign Queue(s)

This property is used to specify the queue(s) to which this activity should be assigned. See section Queue Management for details about managing queues.

The Advanced checkbox at the bottom left of the Assign Queues pop-up window allows workflow administrators to toggle to a different view, where they can configure a given Human Action to be assigned to a Queue dynamically.

The value can be the display name for the queue, or the queue GUID.

Allow Contact

Allow Contact controls whether a link will be shown in request history which allows a user to directly email the assigned resource of this action. Please refer to the system setting ENABLE_DIRECT_CONTACT_TO_WORK_USERS

Activity Timers

This property is used to generate multiple and/or recurring timeout events for the action. Once defined via this field, the defined outputs will be available as output options when setting the properties for links from this action to another. These outputs are not a completion maker, meaning the current activity will continue to process or remain in waiting.

The Time Interval field is used to designate the amount of time after the Action initially executes before following a specified Output path. Use the “+ Add” button to add additional rows as needed to setup multiple timed output options. Each row saved here will result in a corresponding Output option from this particular Human Action in the workflow designer. Like other timer or timeout-based properties in the system, the Time Interval and Recurring Time Interval fields should reflect values in the following format: D.HH:MM:SS

Action Outputs

This property defines the options available to the recipient of a work item created by a Choice activity.

Each row in this Action Outputs window will result in a corresponding output button for the Choice assignee when viewing this work item in their WWL view. And, each row here will also reflect an available transition option when building an output path from this Choice step in the workflow designer.

Just like the Select Task Type property in a Task step, the Action Outputs property enables you to create output button options for this Choice action by either manually adding rows, or by selecting an existing Response Template from the “Load From Template” drop- down menu at the top left to import the output buttons associated with an existing global template. Or, you can even use a combination of both, if needed. (See section below titled “13.2 Response Templates” for details on how to manage the global list of available Action Outputs or Response Templates used to configure a Choice step.)

NOTE: The Load from Template menu function is additive, meaning the existing output buttons associated with the template selected here will be added or appended to any manually entered rows already in the list below.

For each output button/row added to this Choice step, you will need to configure the following properties:

• Button Name* – Designates the display label for this Choice output button (required)

• Completion Maker* – Indicates whether clicking the output button will mark this Choice step as completed; defaults to “Yes” (required)

• Visible* – Designates whether the output button should be displayed for work assignments generated by this Choice step; defaults to “Yes” (required)

• Require Comment* – Designates whether the work assignee will be required to enter text into the “Comments” field before clicking this output button on the Choice work item; defaults to “No” (required)

• Validate Form* – Indicates whether visible form questions shown in the work items details section should be subject to validation when the work assignee clicks this output button on the Choice step; defaults to “Yes” (required)

Once the list of available output buttons looks complete and accurate for this Choice action, click the Save and Close button to save and exit this window.

Work Item Form Configuration

The Work Item Form Configuration property allows you to select and configure the specific form fields to be presented to the work assignee(s) for any given Human Action assigned in a workflow process. The form questions configured via this property will be displayed in the web worklist (WWL) window or when an assignee is viewing a work item.

In the pop-up window for this property, the Limit to Current Workflow checkbox will be checked by default, with the Services drop-down menu showing a list of all forms associated with the current workflow. Selecting a service from that drop-down menu will present a list of existing questions within that service form that can be selected for use in this work item.

However, un-checking the Limit to Current Workflow check box will allow you to browse all the available service forms in the system. From here, you can use the Search field to filter the list of services to locate the desired form, and continue adding questions to the work item list as needed.

Once the desired form is selected in the Services drop-down menu, the questions from that form will be displayed below. Use the checkboxes on the left-hand side to choose the individual question(s) to present to the work assignee(s) in this work item, and click the “+ Add” button. This will display the selected form questions in the area below, where the properties for each question in this work item can be configured.

For each form question/row selected, use the controls provided to designate the following:

• Required (radio set) – indicates whether the work assignee is required to enter a value for this question when completing this work item.
• Default = defer to the attribute as defined in the front-end form editor
• Yes = value is required for this question to complete this work item
• No = value is not required for this question to complete this work item
• As Back-End (checkbox) – indicates whether this question should be editable to the work assignee when processing this work item.
• Read Only (checkbox) – indicates whether this question should be read-only in this work item
• Hidden (checkbox) – indicates whether this question should be visible or hidden in this work item
• Blank Value (checkbox) – indicates whether the previous value provided for this question should be cleared out when presented in this work item

Additional options for the form configuration include the following.

Only show these front-end questions - indicates that only the selected front end questions will be shown

Only show these back-end questions - indicates that only the selected back-end questions will be shown

Only show shared form questions - indicates that only the shared form fields will be shown

Hide shared forms added by other workflow actions - indicates that any shared forms added by other actions in the workflow will be hidden at this step

Use the trash can icon on the right side to delete or remove any question(s) configurations from a given work item.

Return Values

The “Return Values” property allows you to define the various possible output values for the given action. These values can then be used for routing via output paths in the design.

Use the “+ Add” button to enter all applicable Return Values back from the child workflow that might need to be handled in the parent design. Use the trash can icon to delete any individual Return Value row as needed. Once the appropriate values have been entered, click “Save and Close” to save and close the current Return Values management window.

Start

Action Function: The Start action is always the first activity in a workflow design, indicating where the process begins once the workflow is started. When creating a new workflow, the Start action will automatically appear by default in the canvas area of the Workflow Designer window, to provide an initial starting point for the process being modeled.

Action Properties: The Start action is configured by specifying appropriate values for the various available settings in the Action Properties Panel. The Action Properties panel is accessed by selecting the Action Properties option after right-clicking the activity. The specific Action Properties fields available for the Start Action are grouped into related sections as follows:

Label

A display label for the action in the diagram

Properties

Variables

Variables allows for the declaration of values to be used in the workflow instance when the workflow is executed.

These are generally temporary values which are unique to the given workflow instance.

Variables can have any alphanumeric name and support the following types.

String: Any valid string value

Number: Any valid “real” number value

Date: Any valid date. Internally to the application the variable is a “DateTime” and therefore math and other evaluations can be applied to the value.

User: A user in the system, defined by a unique user ID in one of the user directories for which the application is configured. Users are a collection variable and contain various properties for the user based on the User Attributes defined in the application.

Array: an array of values

JSON Object: The JSON object facilitates creation and reading of JSON formatted data through specialized workflow actions and other facilities in the designer.

File: Supports the storage and access to files stored by the engine within its own database as an alternative to storing files within a traditional file system. Various actions support the file variable type as an input or as an output. See the File Assets feature for more information about storing documents for workflow usage.

Additional options for the variables are below.

Has Default* – (Y/N) – Indicates whether a declared variable should be initialized automatically with a default value once the workflow executes (required)

Default Value* – (Alphanumeric) – Designates any default value a declared value should be assigned initially

Use the “+ Add” button at the bottom left of the pop-up window to declare new items, and use the trash can icon on the far right to delete a given item. Once all the desired Variables have been declared for the current workflow, click Save and Close to save the current values and exit this window.

Encrypt - Determines if the workflow variable will be encrypted while stored and obscured when accessed, based on various usages. See Administration, Data Encryption for encryption storage modes.

Encrypted variables provide an additional access method throughout the workflow designer. In addition to the standard

V{{}} 

accessor,

VE{{}}

is also available. This accessor method will provide the raw encrypted data, which may be shown or stored as needed locally or by some remote system.

Please see "Workflow Encryption" for additional notes on encrypting, storing, and accessing encrypted workflow data.

Contents

This property is largely functionally replaced by the “Linked Forms” feature. To easily map form fields to workflow for design time usage, please reference the “Linked Forms” property.

For historical or legacy configurations, Contents refer to any form-submitted data elements from the front-end service request form(s). Any contents that should be passed into the workflow must be identified and mapped through this property setting.

Use the “+ Add” button at the bottom left of the pop-up window to declare new items as needed:

• Name* – Designates the label used to identify the Content element being declared (required)

• Type* – Indicates the type of data associated with the Content item being declared (required):

  • String

  • Number

  • Date

  • Boolean

• XPath* – Identifies the specific path or node within the overall XML output of a form submission that this Content item should be mapped to when retrieving data dynamically (required)

Use the trash can icon on the far right to delete a given Content item as needed. Once all the applicable Content items have been declared for the current workflow, click the Save and Close button to save the current values and exit this window.

Workflow Objects

This property allows for the definition and management of object structures for use within the workflow. Objects provide for the storage and access to complex entities which may contain multiple properties and repeating sets of data which can be used through iteration and other list-based activities. Workflow Objects may be defined visually as a “tree” structure and support internal structure definitions as XML and JSON. Workflow Objects minimize complexities of the specific formats by providing visual access to the object properties throughout the designer. Objects are commonly used to store responses from web services, database calls and similar. The Lists and Iterator features of objects allows for processing of sets of information, useful when “looping” through sets of data, or performing other activities related to sets of repeating information. Iterators are special pointers which are linked to a defined object structure where the object contains repeating values.

Existing Objects and Iterators for the current workflow will be listed on the left-hand side of the Workflow Objects window. Clicking on any of these existing variables will open the details for the selected variable in the center area of this window, where updates can be made as needed.

Click the “+ New” button to create a new Object Variable for use in the current workflow. Required fields for the new object are displayed at the top of the window.

Name – Identifies the new object structure being declared

• Type – Indicates the type of object being declared:

  • Document – Indicates the structure will be set with data

  • Iterator – Indicates the variable is a list pointer inside a repeating section of a Document object

• Storage – When Type = “Document,” this field designates where in the workflow context data for the object will be stored:

  • Variable – The workflow’s Variable storage space will be used to store the object data

  • Content – The workflow’s Context storage space will be used for the object data

Once the selections are made in these fields, click the “Add” button to save the Object Variable definition. At his point, you will be prompted to begin defining the Schema for the new Object.

Manually setting the schema an Object

To setup the Schema for the Object, use the “[+]” link beside the root node, and input the structure manually as needed. For each manually added node row, you can also use the “[-]” button to remove it from the structure at any time. See the section below titled “Modifying the Schema for an Object” for more details.

Double clicking any node label allows the node to be renamed.

Modifying the schema for an Object

From here, you can modify the target Schema as needed, using the “[-]” button to remove any row(s) from the selected form not needed in this Object. Or, clicking the “Toggle Text View” button opens a Text Editor view of the current Schema, to be modified manually as needed to remove any nodes or rows. After modifications are made to the Text View, clicking Save will validate the changes to enforce a valid structure. If that validation fails, you will be presented with a pop-up error message detailing the schema issue(s) that need to be resolved before the new Schema can be saved. Once the Text View of the structure is validated, the original Schema format will display again, reflecting any changes that were made.

NOTE: XML attributes are supported through the Text editor only.

NOTE: XML Namespaces are not supported.

Schemas may be defined with XML or JSON. To manage the schema with a document, select “Toggle Text View” and choose XML or JSON to enter or paste a document to be used.

Workflow Object node visibility

As a convenience feature, workflow objects support the hiding of nodes while using the designer. Workflow objects are commonly fairly large in structure when working with 3rd party APIs, and it is beneficial to store the details of the underlying structure, which can contain information about data types, but for the designer working with the object at design time, the hiding of nodes will remove them from the auto-complete features throughout the designer.

From the schema view for the object, each node provides the option to be hidden.

Click the "eye" icon to toggle visibility for any item.

In the below example, some of the fields are toggled for visibility, which then excludes them in the designer for type-ahead.

The above object with limited visible nodes would be displayed as below using the workflow designer type-ahead feature.

Defining Object Schema with an example document

To define an object schema with an example document, select “Toggle Text View”. Next, select the format of the sample document you wish to use, either XML or JSON. Paste or enter the sample document into the text area provided. Even large sample documents may be used, but they should be reduced to their schema using the “Reduce to schema” link provided below the text area. This will remove any sample data and minimize the document example which is stored with the workflow definition. To see the results of the schema definition, select “Toggle Text View” again to alternate back to the object tree view provided.

Mapping Form fields to XML variables

The preferred method to reference Form values within a workflow is through the “Linked Forms” feature, (see section Linked Forms accessible from the start step property for a given workflow. However, additional methods are available, typically for legacy purposes to map form field values to workflow.

Declaring Iterators

Once any applicable Objects have been declared, you can create matching Iterator variables as needed. An Iterator is required to iterate or loop through the resulting data set stored in an Object within a workflow execution. This would be relevant in the event the data set stored in a document contains one or many repeating nodes.

To create a new Iterator, click the “+ New” button at the top left, and enter values for the required fields at the top:

• Name – Identifies the new Iterator being defined

• Type – Indicates the type of Variable being declared. To create an iterator variable, select Type, “Iterator”

• Scope – When Type = “Iterator,” this field designates the scope of the Iterator within the relevant workflow execution path.

Local – Indicates that each execution branch will persist the “local” or instance value referenced for the iterator distinctly for each entry in the parent document. “Local” is required for parallel iterator execution. Note: The workflow will generate and persist unique variables for all instances of the iterator to the database. It is generally recommended to work with Global scope unless required.

• Global – Indicates that the iterator value will only ever have the current (latest) execution path value at any given time.

Once the appropriate Object is selected in the Document drop-down menu, the schema tied to that Document will display in the Path section below. Using this schema, select the specific repeating node in the Document structure that you want the Iterator to loop through by checking the checkbox beside it.

After clicking the corresponding checkbox to select the node for the Iterator action to loop through, click Save to save the current Iterator record. For any Document or Iterator selected from the list on the left, you can click the Delete button to delete the entire record at any time. Upon doing so, you will be prompted with a pop-up message asking you to confirm the deletion before it is completed.

Once all the desired Objects and corresponding Iterators have been defined for the current workflow, click Save & Close.

Workflow Events

The Workflow Events and “Finish Marker” action provide capability to manage workflows which finish unexpectedly (due to an unhandled action output, error, or other condition). This feature can reduce the design requirements to actively manage ‘negative path’ conditions. Workflows can finish for several reasons at any point in the process, i.e. executing a database query which fails, or assigning a task to a resource which could not be found. Workflows in this state tend to either end as “finished successfully” or as “finished with errors” depending on whether the failing action would error or output a condition which wasn’t mapped in the design. By use of this feature, workflows can trigger one or more alert emails, have a status set, or initiate another workflow to manage the condition. While it is still recommended to have designed processes to support expected failures, based on the workflow requirements, it may not be necessary to have error handling configured for every single action, or type of actions, such as a series of database calls.

Note: In addition to Workflow Events, controls may be set more specifically for Action Events. See “Action Events” for more information.

Usage

Workflow events are managed per workflow definition and are defined from the “Start” step, Workflow Events property.

To add a finished workflow event action, choose the type of action to take, “Send Email, Set Status, or Start Workflow” and click “Save”.

Each action selected will present options for which event will trigger the action. The events are as follows.

Reached finish marker (or there was not one and there were no errors). This event occurs if the workflow contains a finish marker action and the action was reached, or if no finish marker is present within the workflow and the workflow has finished.

Did not reach finish marker. This event occurs if a finish marker action is present within the workflow and the workflow has finished without reaching the marker.

Finished with errors. This event occurs if any workflow action has executed with errors.

Each action provides parameters based on the action type selected.

Send Email. The Email action event takes parameters for the recipient, email subject, and email body. Workflow values from the finished workflow can be used within these parameters as needed.

Start Workflow. This event will start a workflow when the conditions have been met. For this option, select which to start, as well as any optional data to be sent to the started worfklow. Options for the called workflow data include setting Workflow ID, Name, Status and State to the specified called workflow variables. Options for the workflow are below.

Call as child workflow – indicates the workflow will be executed as if called by the respective workflow instance triggering the event

Send this workflow’s variables – indicates that any variables of matching names in the triggering workflow will be copied to the new workflow instance

Use this workflow’s content – indicates that the started workflow contents will be set to a copy of the triggering workflow contents

Add this content – provides for specific contents to be set as the new workflow contents

Additional workflow data transfer

When starting a new workflow from a workflow event, the calling workflow’s values can be sent to the new workflow into target variables. The starting workflow’s ID, Name, Status, and State may be optionally handed to the new workflow.

Workflow Events for In Process Workflow Mode

Workflow Events are supported for "In Process/In Memory" execution mode. To enable workflow events for this mode, use the system setting, ENABLE_WORKFLOW_EVENTS_FOR_INPROC. With this setting enabled, options are made available for the handling of workflows ran when triggered from workflow events, via the Start Event Workflow As option.

Milestones

Milestones provide a method to define linear, fixed, named stages of execution for workflows. As the stages are declared in advance and are fixed, users can be shown the current state of the workflow, which stages have completed, and which ones remain. The milestone data is also available for roll-up reporting. Milestones can be shown to end users through supporting areas of the application as well as widgets which will render the milestone data. Once the stages are defined in the Milestone property window, these stages are then available to the milestone action when used in the diagram for this workflow. Called workflows may also control the milestone progression for a workflow. See the Milestone Widget and the Milestone workflow actions for more information.